TextArea

Represent a control where you can add/modify a text:

To create a textarea use TextArea::new method (with 3 parameters: a caption, a layout and initialization flags).

let tx = TextArea::new("Some text", layout!("x:10,y:5,w:15"), textarea::Flags::None);

or use the macro textarea!()

let textarea1 = textarea!("text='some text to edit',a:c,h:100%");
let textarea2 = textarea!("'some text to print',a:c,h:100%,flags:ReadOnly");

A textarea supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Parameter name Type Positional parameter Purpose
text String Yes (first postional parameter) The text from a text area. If ommited an empty string will be considered as the caption of the textarea.
flags List No TextArea initialization flags that control how the TextArea should look and behave(ReadOnly, having line numbers)

Text Area supports the following initialization flags:

  • textarea::Flags::ShowLineNumber or ShowLineNumber (for macro initialization) - This flag enables the display of line numbers in the text area, typically in a gutter on the left side. It helps users keep track of their position within the text, making navigation and debugging easier. This feature is especially useful for programming and document editing, where line references are important.
  • textarea::Flags::ReadOnly or ReadOnly (for macro initialization) - When this flag is set, the text area becomes non-editable, meaning users can view but not modify the text. This is useful for displaying logs, reference documents, or any content where accidental modifications should be prevented. Although users cannot change the text, they may still be able to select and copy it.
  • textarea::Flags::ScrollBars or ScrollBars (for macro initialization)- This flag enables scrollbars in the text area when the content exceeds the visible space. It ensures smooth navigation by allowing users to scroll horizontally or vertically as needed.
  • textarea::Flags::HighlightCursor or HughlightCursor (for macro initialization) - When enabled, this flag highlights the current cursor position within the text. It can be useful for visually tracking the insertion point while typing or editing. The highlight will appear as a different background color.

Methods

Besides the Common methods for all Controls a textfield also has the following aditional methods:

Method Purpose
set_text Replaces the current content with the specified text.
insert_text Inserts the given text at the specified cursor position.
remove_text Removes a portion of the text between specified positions.
text Returns the full content of the text editor.
select_text Selects a range of text with the given start position and size.
clear_selection Clears any active text selection.
has_selection Returns true if there is an active text selection.
selection Returns the currently selected text, if any.
delete_selection Deletes the currently selected text.
is_read_only Returns true if the text editor is in read-only mode.
set_cursor_position Moves the cursor to the specified position.
cursor_position Returns the current position of the cursor.

Key association

The following keys are processed by a TextField control if it has focus:

Key Purpose
Arrow Keys Move the cursor left, right, up, or down by one character or line.
Shift + Arrows Extends the text selection in the direction of the arrow key.
Ctrl + Right Moves the cursor to the beginning of the next word.
Ctrl + Left Moves the cursor to the beginning of the previous word.
Ctrl + Shift + Right Extends the selection to the beginning of the next word.
Ctrl + Shift + Left Extends the selection to the beginning of the previous word.
Ctrl + C Copies the selected text to the clipboard.
Ctrl + V Pastes the clipboard content at the cursor position.
Backspace Deletes the character before the cursor.
Delete Deletes the character after the cursor.
Ctrl + Backspace Deletes the entire previous word.
Ctrl + Delete Deletes the entire next word.
Enter Inserts a new line at the cursor position.
Page Up Moves the view up by one page, scrolling the text accordingly.
Page Down Moves the view down by one page, scrolling the text accordingly.

Aditionally, all printable characters can be used to insert / modify or edit the current text.

Mouse actions

Mouse cursor can be used to select the text.

Example

The following code creates multiple text areas with both unicode and regular text.

use appcui::prelude::*;

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    let mut w = Window::new("Title", layout!("a:c,w:40,h:11"), window::Flags::None);
    w.add(TextArea::new("I ❤️ Rust Language", layout!("a:c,h:100%"), textarea::Flags::None));
    w.add(TextArea::new("Read only text", layout!("a:c,h:100%"), textarea::Flags::ReadOnly));
    w.add(TextArea::new("Line Numbers tab functional", layout!("a:c,h:100%"), textarea::Flags::ShowLineNumber | textarea::Flags::ReadOnly));
    w.add(TextArea::new("I also have scrollbars ❤️", layout!("a:c,h:100%"), textarea::Flags::ScrollBars));
    a.add_window(w);
    a.run();
    Ok(())
}